fix(schemas): stop design.md from restating the proposal#1401
Conversation
The spec-driven design instruction asked for background, current state, and goals without saying the motivation and scope already live in proposal.md, so generated designs often duplicated the proposal instead of adding technical decisions. Scope the Context and Goals guidance to what the approach needs, and state the boundary explicitly: the proposal covers why and what, design covers how - reference, don't restate. Closes #1382 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe spec-driven schema now distinguishes proposal responsibilities from design responsibilities, limits duplicated context, and clarifies design decision guidance. The design template references ChangesProposal and design guidance
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@schemas/spec-driven/schema.yaml`:
- Around line 129-131: Align the guidance with the design dependency by updating
the design requirements near the proposal/specs instructions to include specs in
design.requires, ensuring specs exist before design generation. Preserve the
existing proposal dependency and avoid changing unrelated documentation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 9d5c7bf3-79f7-4813-9856-42deefe78c8e
📒 Files selected for processing (2)
schemas/spec-driven/schema.yamlschemas/spec-driven/templates/design.md
design.requires is [proposal] only, so a design can be drafted before the specs exist. Say "once written" instead of implying the specs are always there to reference. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
alfred-openspec
left a comment
alfred-openspec
left a comment
There was a problem hiding this comment.
The proposal/design boundary is now explicit without changing the existing parallel artifact ordering, and the template mirrors the schema guidance. Exact-head build plus 96 focused schema, resolver, and instruction-loader tests passed.
…ndary schemas/ ships in the npm package files list, so this guidance change reaches users on upgrade and needs a changelog entry. The Validate Release Tracking check only validates changesets when present, so its absence was not caught. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
alfred-openspec
left a comment
alfred-openspec
left a comment
There was a problem hiding this comment.
The added patch changeset accurately captures the user-visible schema guidance change, and its parent is the previously reviewed head. Full exact-head CI is green; approval restored.
2 participants
Status: Ready for review. Guidance-only change to the default
spec-drivenschema - no code paths, no CLI behavior, no schema structure changes.What was wrong: #1382 - in the default schema,
proposal.mdanddesign.mdoften end up saying the same thing. The design instruction asked for "Background, current state, constraints, stakeholders" and "What this design achieves and excludes" without ever saying that motivation and scope already live in the proposal, so agents dutifully restated the proposal's Why and What Changes instead of adding the design's differentiated value (approach, alternatives, trade-offs). The proposal side already had its boundary line ("implementation details belong in design.md"); the design side had no equivalent.How it was fixed: Two files, wording only:
schemas/spec-driven/schema.yaml(design instruction): Context is scoped to "only the current state and constraints needed to explain the approach," with a cross-reference example ("See proposal.md - Why"); Goals / Non-Goals now says not to restate the proposal's scope; the closing guidance states the boundary explicitly - the proposal covers why and what, design covers how; reference rather than restate.schemas/spec-driven/templates/design.md: section comments mirror the same boundary, and the Decisions comment now mentions alternatives considered.The third acceptance criterion in #1382 (alternatives and trade-offs as first-class decision content) was already met by the existing instruction ("Include alternatives considered for each decision") - this PR only surfaces it in the template comment.
Proof it works:
schemas/ships verbatim in the npm package and is parsed at runtime, so there are no compiled copies or golden hashes to regenerate (same shape as #1326 and #1366). Verified:schema.yamlstill parses (artifacts:proposal,specs,design,tasks)npm run build: 2,027 passed; the only 17 failures are the pre-existing environment-onlyzsh-installerones tracked in ZshInstaller tests fail on machines with a real Oh My Zsh install (17/50 failures) #1321 / PR test(completion): isolate ZshInstaller tests from a real Oh My Zsh install #1400, identical onmainskill-templates-parity,artifact-graph/resolver, andinstruction-loadertests all greenNotes: Deliberately does not touch the proposal instruction (its boundary line already exists, and #1399 currently has open edits in that section). Design/architecture untouched - this clarifies the schema's existing intent (the instruction already said "Reference the proposal for motivation").
Closes #1382
🤖 Generated with Claude Code
Summary by CodeRabbit